Apéndice B · ADR
Registro de decisiones de arquitectura
Este ADR es un borrador de trabajo, no una arquitectura aprobada. Las decisiones marcadas Propuesta y Pendiente deben validarse y resolverse como parte de las primeras tareas del kickoff del proyecto (Feature 0), conforme al calendario de colaboración de la propuesta (sección 06). Nada aquí se implementa como definitivo antes de esa validación.
NetPay ya opera infraestructura en AWS (S3, conexiones a Salesforce, componentes en construcción del bot de merchants) y su área de seguridad/arquitectura tiene a AWS pre-aprobado ("safe check"). El requerimiento pedía compatibilidad con Bedrock.
Todo el programa se construye sobre la cuenta AWS de NetPay: Bedrock (LLM: Claude; Knowledge Base para RAG), Lambda, DynamoDB, S3, S3 Vectors, Secrets Manager, CloudWatch, End User Messaging Social para WhatsApp, y Amazon Connect en Fase 2.
Plataformas de agentes de terceros con deployment acelerado: descartadas como base del entregable final para evitar fricción de seguridad y compatibilidad; pueden usarse como herramienta de prototipado (ver ADR-008).
Volumen actual: ~445 socios, ~411 prospectos/mes, ~400 consultas/mes. NetPay contempla a futuro un auto-onboarding a mercado abierto que "cambiaría los números drásticamente", pero declaró explícitamente que no es la intención en esta etapa.
Arquitectura serverless dimensionada para la escala actual con margen razonable (Lambda + DynamoDB on-demand escalan solos ante picos moderados), sin sobre-ingeniería de alta concurrencia.
El requerimiento original ubicaba en S3 el estatus en tiempo real y la lógica de permisos. S3 es almacenamiento de objetos: sirve como destino de consolidación, pero no es autoritativo sobre datos que mutan en Salesforce o en el Core. Un estatus con rezago batch degrada la confianza en el canal; permisos evaluados sobre copias planas desincronizadas implican riesgo de exposición cruzada entre socios.
Las consultas transaccionales (prospectos, contratos, expedientes, SLA, tickets) se leen del sistema que administra el dato — Salesforce durante este programa — a través de la capa de abstracción (ADR-005). S3 se usa para: (a) el contenido de la base de conocimiento del RAG, (b) documentos y bitácoras. La autorización nunca se evalúa sobre copias planas (ADR-004).
Hoy no existe mecanismo de autenticación. El número de celular es de baja fricción pero portable y suplantable: no puede ser factor único para exponer expedientes y contratos. NetPay valoró explícitamente que la propuesta incluyera autenticación (único proveedor que lo contempló).
Clasificación de datos por sensibilidad: información de bajo riesgo con identificación por celular registrado; datos de cuenta/expediente/contrato exigen ID de Socio Comercial como segundo factor. La autorización Socio/Master ↔ cuenta/company/branch se evalúa del lado servidor en cada consulta, contra la fuente autoritativa de la relación. Toda consulta queda en bitácora de acceso auditable. Revocación de permisos surte efecto en la siguiente consulta (sin sesiones privilegiadas persistentes).
Salesforce es la fuente de verdad hoy, pero NetPay contempla cuestionar/evolucionar sus plataformas a futuro, y el rediseño del bot de merchants interviene workflows de Salesforce compartidos durante la ejecución de este programa.
El orquestador del agente nunca consulta Salesforce (ni otras fuentes) directamente: lo hace a través de una capa de abstracción con interfaz por dominio (prospectos, contratos, tickets, SLA, cotizaciones) y adaptadores intercambiables por sistema de origen.
En Fase 2 el agente pasa de leer a escribir en sistemas de registro (prospectos, tickets, cambios de datos, pedidos). Los reintentos de red en WhatsApp y la naturaleza conversacional generan riesgo de operaciones duplicadas o no intencionadas.
Patrón obligatorio para toda escritura: (1) confirmación explícita del usuario con resumen de la operación; (2) claves de idempotencia — un reintento no duplica; (3) bitácora de toda operación con datos previos/posteriores; (4) procedimiento de reversión documentado por tipo de operación.
El cotizador es la capacidad angular del programa. NetPay definió el comportamiento esperado: recomendación inteligente basada en el histórico de cotizaciones aprobadas por pricing (giro, volumen, ticket promedio → condiciones típicas de cierre), no un formulario de preguntas básicas.
- Ground truth: el histórico de cotizaciones aprobadas por pricing (18–24 meses) se asume correcto y es la base de entrenamiento/inferencia.
- Preprocesamiento: la data se ingesta, homologa y digiere previamente (no se calcula "al vuelo" en cada consulta — costo por token y latencia); el agente consume el resultado estructurado.
- Límites duros: la recomendación opera dentro de piso/techo por reglas de negocio. Dentro de límites → el agente entrega. Fuera de límites → lo declara, genera ticket y escala a pricing. El agente nunca aprueba condiciones fuera de política.
- Cotización sin registro: se puede cotizar de manera exploratoria sin crear formalmente un prospecto; el alta formal es un paso posterior y separado.
- POC en Feature 0 valida el diseño con data real antes del desarrollo del Feature 6.
DashOne dispone de agentes de WhatsApp pre-construidos (knowledge base, skills) desplegables en minutos, útiles para validar experiencia y contenido tempranamente. NetPay quiere velocidad de validación sin comprometer el destino final del sistema.
Los mockups, POCs y validaciones tempranas pueden ejecutarse sobre herramientas de prototipado de DashOne. Todo componente productivo se entrega desplegado en la cuenta AWS de NetPay, bajo sus controles. La migración prototipo → producción es responsabilidad de DashOne dentro del alcance cotizado.
NetPay decidió sacar el piloto rápido por un camino alternativo, sin integrarlo a su plataforma global de agentes, cuyo diseño/roadmap está fuera del control de este programa.
El agente opera de forma autónoma respecto a la plataforma global. No se construyen integraciones hacia ella en ninguna de las dos fases.
El requerimiento pide entregar accesos, contraseñas y API keys por el canal, descartando un portal. WhatsApp cifra en tránsito, pero el lado business y sus bitácoras ven el contenido, y una cuenta secuestrada expone todo lo entregado. Con la restricción de "100% WhatsApp", la salida estándar (enlace a portal autenticado) no está disponible.
- (a) Enlace efímero de un solo uso con verificación adicional (segundo factor) — portal mínimo, técnicamente fuera de la restricción estricta.
- (b) Entrega en canal con secreto parcial + activación por vía separada.
- (c) Entrega en canal con expiración/rotación forzada inmediata post-primer-uso.
Diferida al área de seguridad de NetPay, con acompañamiento de diseño de DashOne. El Feature 8 se construye alrededor del mecanismo autorizado.
Ambos proyectos comparten cuenta AWS, equipo del cliente, ventana de tiempo y — crítico — workflows de Salesforce que este programa lee y el otro modifica.
Se establece: (1) interlocutor único del lado merchants con obligación de aviso previo de cambios a objetos/workflows compartidos; (2) registro de dependencias externas revisado al cierre de cada feature; (3) guidelines de desarrollo alineados y componentes comunes reutilizables donde el diseño lo permita (disposición ya manifestada por DashOne).
Resumen de estatus
| ADR | Título | Estatus | Acción requerida de NetPay |
|---|---|---|---|
| 001 | AWS + Bedrock como base | Aceptada | — |
| 002 | Dimensionamiento a red actual | Aceptada | — |
| 003 | S3 no autoritativo; lecturas transaccionales | Propuesta | Confirmar existencia/frecuencia del S3 consolidado (sem 2) |
| 004 | Identificación + 2º factor; auth server-side | Propuesta | Ratificar ID de Socio como 2º factor (F0) |
| 005 | Capa de abstracción con adaptadores | Propuesta | Validación técnica (F0) |
| 006 | Escrituras: confirmación + idempotencia + reversión | Propuesta | Validación técnica (F0) |
| 007 | Cotizador acotado por reglas + escalamiento a pricing | Lógica ✓ D8 abierta | Entregar data histórica (sem 1–2); decidir D8 con la POC |
| 008 | Prototipado acelerado, entrega en infra NetPay | Propuesta | Validación técnica (F0) |
| 009 | Piloto desconectado de plataforma global | Aceptada | — |
| 010 | Mecanismo de credenciales | Pendiente | Decisión de seguridad, semana 2 — bloquea F8 |
| 011 | Interfaz con bot de merchants | Propuesta | Designar interlocutor (sem 1) |
Validación de cierre — al término del Feature 0
| Rol | Nombre | Firma | Fecha |
|---|---|---|---|
| Responsable técnico / seguridad · NetPay | |||
| Arquitectura · DashOne |
Las decisiones aquí registradas gobiernan la implementación. Cambios posteriores a la validación se registran como nuevos ADRs y, si alteran alcance o esfuerzo, pasan por control de cambios.